Introduce deprecated coroutine builder overloads accepting a Job by dkhalanskyjb · Pull Request #4435 · Kotlin/kotlinx.coroutines

dkhalanskyjb · 2025-05-13T13:28:29Z

This is a small step towards deprecating the practice of breaking
structured concurrency by passing a Job to a coroutine builder.

Thanks to @LouisCAD for the idea!

See #3670

LouisCAD · 2025-05-13T14:13:46Z

Awesome stuff!

lukellmann · 2025-05-17T11:41:14Z

+ *                 throw IllegalStateException("$it is tired of all this")
+ *             }
+ *         }
+ *         coroutines.joinAll()


Why do an explicit join here? supervisorScope should wait for its children, right?

Yes, it will. The idea was to highlight how joinAll will not fail in this scenario, but this piece of documentation may not be a good place for that.

This was also confusing to me. A simple comment on this line // joining failed supervised coroutines doesn't fail either would help!

lukellmann · 2025-05-17T12:02:45Z

+ * scope.async(start = CoroutineStart.ATOMIC) {
+ *     withContext(NonCancellable) {
+ *         // this line will be reached even if the parent is cancelled
+ *     }
+ *     // note: the cancellation exception *can* be thrown here,
+ *     // losing the computed value!
+ * }


Does that mean you can loose the value, even if there is no code after the withContext block?

scope.async(start = ATOMIC) { withContext(NonCancellable) { dontWantToLooseThisResource() } // no code here, or only code without suspension points }

The documentation for withContext says there will be no cancellation on entry/exit with NonCancellable.

My comment is misleading, but yes, the value can be lost, just not because of withContext. The problem is that if the Deferred is cancelled before returning a value, it will no longer be able to finish with a value, even if the computation succeeds.

Ok, that's a bit surprising to me. I guess it's because it could have children that haven't completed yet?

Nope, even without any children: https://pl.kotl.in/-ZYf_PR9z
The reason can be seen in the diagram in https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/ : once a Job gets cancelled, there is no way back to being Active or Completing or returning a value.

Makes sense, good to know 👍

I think it'd make sense to make an overload to specifically accepts NonCancellable. It's doable since NonCancellable is not just a Job instance, but an object that has its own exclusive type.

That overload could then have the KDoc just for this use case, and could also have a matching ReplaceWith clause.

lukellmann · 2025-05-18T12:46:17Z

+ * } finally {
+ *     // if `await` fails because the current job is cancelled,
+ *     // also cancel the now-unnecessary computations
+ *     deferred.cancel()


Should it be pointed out that just calling cancel on deferred won't prevent the current coroutine from completing before the now cancelled coroutine in the other scope completes?

LouisCAD · 2025-05-19T09:21:40Z

With these changes, someScope.launch(NonCancellable) { ... } will no longer compile. I've yet to see a tangible use case for that, where the someScope is useful (for anything but Job, that'd be), but wanted to point it out.

Another construct could be thought out, or an overload taking the NonCancellable type could be introduced, if that actually needs to be addressed.

dkhalanskyjb · 2025-05-19T10:23:10Z

@LouisCAD, what is the compilation error? I've just checked, and launch(NonCancellable) compiles for me (with a warning, as intended). I consider launch(NonCancellable) to be incorrect, with launch(start = CoroutineStart.ATOMIC) { withContext(NonCancellable) { /* computation */ } } being a strictly better version of the same.

LouisCAD · 2025-06-18T12:14:23Z

Right, it compiles with just a warning.
For some reason, I thought the deprecation level was error, though I guess that is where it's headed, fast forward into the future.

Came back here to comment about a specific use case I just had.

In the snippet below, I want an async that contains its crashes to await()/join() calls on the resulting Deferred, and doesn't bubble it up to its parents.
I can't use supervisorScope { … } this time, so I'm using this:

async(SupervisorJob(coroutineContext.job)) { // this (the receiver) is a `CoroutineScope`
    // Some throwing code
}

With those changes, it'd trigger a warning, even though it's technically correct.

Addressing #4329 would provide a good alternative, though.

murfel · 2026-02-18T14:32:44Z

+/**
+ * Deprecated version of [future] that accepts a [Job].
+ *
+ * See the documentation for the non-deprecated [future] function to learn about the functionality of this function.


Is there a way to fully-qualify the non-deprecated [future], so that it's clickable? Currently, it stays on the same page if I click on it in the kdoc in the IDE.

And the deprecated [async] below shows the non-deprecated async kdoc, confusingly.

I noticed that we don't really care about navigability of kdocs. If so, is it because of some technical difficulties outside of kx.coroutines control?

There isn't any way to affect the resolution here, unfortunately. Not only do we not have control over this, but also, the resolution results may be different between the IDE and the rendered html documents.

In such cases, there's an argument to be made for not leaving a link at all. However, my preferred design for the improved KDoc navigability includes warnings for ambiguous cases. With that in mind, I'm hopeful that one day, after we upgrade to a new Kotlin version, we'll see a hundred "ambiguous reference in KDoc" warnings and will be able to easily audit and fix them.

murfel · 2026-02-18T14:32:48Z

+ *
+ * It is incorrect to pass a [Job] as [context] to [produce], [async], or [launch],
+ * because this violates structured concurrency.
+ * The passed [Job] becomes the sole parent of the newly created coroutine, which completely severs the tie between


"completely severs the tie" -> "removes the parent-child relationship"

The target audience for this is people who don't have a solid grasp on structured concurrency yet. To them, "parent-child relationship" may be a phrase devoid of special meaning. The dramatic "severs the tie" phrasing is intended to clearly describe the stakes: one piece of code is completely unaware of the other. The more experienced users can be expected to understand the specifics from the "sole parent" remark.

murfel · 2026-02-18T14:32:50Z

+ * - The [CoroutineScope] can only complete when all its children complete.
+ *   If the [CoroutineScope] is lexically scoped (for example, created by [coroutineScope], [supervisorScope],
+ *   or [withContext]), this means that
+ *   the lexical scope will only be exited (and the calling function will finish) once all child coroutines complete.


Points 1-3 are explanation to why "cancellation of the parent job cancels the children" is useful, and point 4 is an independent one. Consider moving points 1-3 into sub-points.

Then your structure will be: structured concurrency ensures

A cancelled parents cancel children (A is important because 1, 2, 3)

B parent waits for children

See a note on lifecycle below, related to this section.

These two notes are the only non-trivial comments, requesting changes in this section (and other sections referring to this one.)

This section establishes the ground rules, and the following sections should refer to arguments listed here.

The whole narrative is like this:

Passing a Job explicitly prevents structured concurrency, don't do it, we are about to give you a collection of samples to use instead.

Defining structured concurrency (parent-child relationship), various implications of parent-child relationship, and what scenarios they prevent or enable.

List of samples, each sample demonstrates how it preserves structured concurrency.

Currently, the structured concurrency section defines things more loosely and doesn't precisely match with the arguments in the samples.

The more robust separation would be 1,2,3-cancellation, 4-completion, because in 3, the cancellation also goes the other way, from the child to the parent. I don't understand the benefits of such a grouping, though.

In response to your proposal, I did change the structure a bit to flow more naturally, though I'm not sure that it aligns with what you had in mind.

murfel · 2026-02-18T14:32:52Z

+ *
+ * Sometimes, it is undesirable for the child coroutine to react to the cancellation of the parent: for example,
+ * some computations have to be performed either way.
+ * `produce(NonCancellable)` or `produce(Job())` can be used to achieve this effect.


It's unclear if this is what you should do, or what you should avoid.

murfel · 2026-02-18T14:32:53Z

+ * some computations have to be performed either way.
+ * `produce(NonCancellable)` or `produce(Job())` can be used to achieve this effect.
+ *
+ * Alternative approaches that preserve structured concurrency are this:


Suggested change

* Alternative approaches that preserve structured concurrency are this:

* Here's an alternative approach that preserves structured concurrency:

murfel · 2026-02-18T14:33:04Z

+ *             // are only available through `channel`
+ *         }
+ *     }
+ *     // this line will only be reached when the `produce` coroutine complete


murfel · 2026-02-18T14:33:07Z

+ * // this line will be reached when both `launch` and `produce` complete
+ * ```
+ *
+ * All of these approaches preserve the ability of a parent to cancel the children and to wait for their completion.


I like this very succinct summary of why we need to strive to preserve structured concurrency.

murfel · 2026-02-18T14:33:12Z

+ *
+ * ```
+ * GlobalScope.produce {
+ *     // this is explicitly a rogue computation


I don't like the term rogue. It's emotionally charged and doesn't hint at what it means. Possibly, an orphaned coroutine would work better? Did we leak this to outside documentation already, or is there a room for negotiation?

In this particular case no need to decide now, we could just say: this computation doesn't have a parent, and thus cannot be cancelled.

murfel · 2026-02-18T15:02:35Z

+ * Alternative approaches that preserve structured concurrency are this:
+ *
+ * ```
+ * // Guarantees the completion


A bit verbose given L550?
If you decide to keep, then also add it in launch.

murfel · 2026-02-18T15:09:33Z

+ *                 throw IllegalStateException("$it is tired of all this")
+ *             }
+ *         }
+ *         coroutines.joinAll()


This was also confusing to me. A simple comment on this line // joining failed supervised coroutines doesn't fail either would help!

This is a small step towards deprecating the practice of breaking structured concurrency by passing a `Job` to a coroutine builder. See #3670

Co-authored-by: Luca Kellermann <lukellmann@gmail.com>

dkhalanskyjb requested a review from qwwdfsad May 13, 2025 13:28

lukellmann reviewed May 18, 2025

View reviewed changes

dkhalanskyjb mentioned this pull request Jun 20, 2025

Utility for creating child scopes #2758

Open

dkhalanskyjb requested a review from murfel December 22, 2025 14:57

murfel requested changes Feb 18, 2026

View reviewed changes

dkhalanskyjb mentioned this pull request Mar 23, 2026

Deprecate NonCancellable in favor of a new scoped function #4643

Open

dkhalanskyjb and others added 6 commits March 26, 2026 10:37

Introduce deprecated coroutine builder overloads accepting a Job

d6e289e

This is a small step towards deprecating the practice of breaking structured concurrency by passing a `Job` to a coroutine builder. See #3670

API dump

e9cbfa9

Apply suggestions from code review

85285f1

Co-authored-by: Luca Kellermann <lukellmann@gmail.com>

Improve wording

2805524

Add extra async/launch overloads for NonCancellable

5f850e7

Improve doc clarity

cd1e3b6

dkhalanskyjb force-pushed the dkhalanskyjb/launch-async-no-job branch from 1357b31 to cd1e3b6 Compare March 26, 2026 10:27

dkhalanskyjb merged commit 378e3a4 into develop Mar 30, 2026
1 check failed

dkhalanskyjb deleted the dkhalanskyjb/launch-async-no-job branch March 30, 2026 10:03

	* Alternative approaches that preserve structured concurrency are this:
	* Here's an alternative approach that preserves structured concurrency:

Conversation

dkhalanskyjb commented May 13, 2025

Uh oh!

LouisCAD commented May 13, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LouisCAD commented May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dkhalanskyjb commented May 19, 2025

Uh oh!

LouisCAD commented Jun 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

LouisCAD commented May 19, 2025 •

edited

Loading